Skip to main content

Getting Started for Developers

Welcome to Net Protocol development! This guide will help you understand how to build applications on top of Net's decentralized messaging infrastructure.

Net Protocol Overview​

Net is a decentralized onchain messaging protocol that enables applications to store and retrieve data directly on blockchain networks. The core contract is deployed at the same address across multiple EVM chains:

Contract Address: 0x00000000B24D62781dB359b07880a105cD0b64e6

Integration Pattern​

To build on Net, your application contract needs to:

  1. Import the Net contract
  2. Send messages using sendMessageViaApp
  3. Query messages using Net's indexing system
import {Net} from "./Net.sol";

contract YourApp {
    Net internal net = Net(0x00000000B24D62781dB359b07880a105cD0b64e6);

    function sendData(string calldata text, string calldata topic, bytes calldata data) external {
        net.sendMessageViaApp(msg.sender, text, topic, data);
    }
}

Message Structure​

Every message in Net follows this standardized structure:

struct Message {
    address app;        // Your contract address
    address sender;      // User who triggered the action
    uint256 timestamp;   // Block timestamp when sent
    bytes data;          // Your application's data
    string text;         // Human-readable text
    string topic;        // Category for indexing
}

Multi-Dimensional Indexing System​

Net creates four types of indexes for each message, enabling efficient querying:

Note: You don't need to understand the indexing details to use Net, but here's some information in case you're interested in how the system works:

Index Types​

  1. App Index: keccak256(abi.encodePacked(app)) - Messages from an app (indexed by position within app's message list)
  2. App + User Index: keccak256(abi.encodePacked(app, user)) - User's messages in an app (indexed by position within user's message list in that app)
  3. App + Topic Index: keccak256(abi.encodePacked(APP_TOPIC_HASH_PREFIX, app, topic)) - App messages by topic (indexed by position within app's messages for that topic)
  4. App + User + Topic Index: keccak256(abi.encodePacked(APP_USER_TOPIC_HASH_PREFIX, app, user, topic)) - User's messages in app by topic (indexed by position within user's messages for that topic in that app)

Hash Prefixes​

  • APP_TOPIC_HASH_PREFIX = 1 - Prevents collisions between topic and non-topic hashes
  • APP_USER_TOPIC_HASH_PREFIX = 2 - Prevents collisions in user-topic combinations

Querying Use Cases​

The multi-dimensional indexing enables querying by index position within each dimension:

App Index - Query messages by index position within an app's message list:

// Get message at index idx from app's message list
getMessageForApp(idx, appAddress)

App + User Index - Query messages by index position within a user's message list in an app:

// Get message at index idx from user's messages in app
getMessageForAppUser(idx, appAddress, userAddress)

App + Topic Index - Query messages by index position within an app's messages for a specific topic:

// Get message at index idx from app's messages for topic
getMessageForAppTopic(idx, appAddress, topic)

App + User + Topic Index - Query messages by index position within a user's messages for a specific topic in an app:

// Get message at index idx from user's messages for topic in app
getMessageForAppUserTopic(idx, appAddress, userAddress, topic)

Each index maintains its own ordered list of message indexes, enabling efficient retrieval by position within that specific dimension.

Sending Messages​

Net provides two ways to send messages:

Direct Messages (sendMessage)​

Users send messages directly to Net Protocol:

function sendMessage(
    string calldata text, // Human-readable message
    string calldata topic, // Message category
    bytes calldata data   // Binary data payload
) external

Use Cases:

  • Users sending messages directly
  • No app contract involved
  • App field set to address(0)

Events Emitted:

  • MessageSent(address indexed sender, string indexed topic, uint256 messageIndex)

App Messages (sendMessageViaApp)​

Applications send messages on behalf of users:

function sendMessageViaApp(
    address sender,      // User address (app chooses this)
    string calldata text, // Human-readable message
    string calldata topic, // Message category
    bytes calldata data   // Binary data payload
) external

Use Cases:

  • Applications sending messages for users
  • App contract controls the sender parameter
  • App field set to calling contract address (msg.sender)

Events Emitted:

  • MessageSentViaApp(address indexed app, address indexed sender, string indexed topic, uint256 messageIndex)

Trust Model for App Messages​

When using sendMessageViaApp, the app contract controls the sender parameter:

  • App controls sender: The app can set any address as the sender
  • Verification: Trust in message authenticity depends on trusting the app contract
  • Open source apps: Easier to verify behavior and trustworthiness
  • Closed source apps: Requires more careful evaluation of the app's reputation and behavior

Querying Messages​

Net provides multi-dimensional querying capabilities:

Single Message Queries​

  • getMessage(uint256 idx) - Get message by global index (from messagePointers array)
  • getMessageForApp(uint256 idx, address app) - Get message at index idx from app's message list
  • getMessageForAppUser(uint256 idx, address app, address user) - Get message at index idx from user's messages in app
  • getMessageForAppTopic(uint256 idx, address app, string topic) - Get message at index idx from app's messages for topic
  • getMessageForAppUserTopic(uint256 idx, address app, address user, string topic) - Get message at index idx from user's messages for topic in app

Range Message Queries​

Range queries retrieve multiple messages by index range within each dimension:

  • getMessagesInRange(uint256 startIdx, uint256 endIdx) - Get messages by global index range (from messagePointers array)
  • getMessagesInRangeForApp(uint256 startIdx, uint256 endIdx, address app) - Get messages by index range within app's message list
  • getMessagesInRangeForAppUser(uint256 startIdx, uint256 endIdx, address app, address user) - Get messages by index range within user's messages in app
  • getMessagesInRangeForAppTopic(uint256 startIdx, uint256 endIdx, address app, string topic) - Get messages by index range within app's messages for topic
  • getMessagesInRangeForAppUserTopic(uint256 startIdx, uint256 endIdx, address app, address user, string topic) - Get messages by index range within user's messages for topic in app

Range queries use startIdx (inclusive) and endIdx (exclusive) parameters. The range must be within the bounds of the specific dimension's message list.

Count Functions​

Count functions return the total number of messages in each dimension:

  • getTotalMessagesCount() - Total messages in system (messagePointers.length)
  • getTotalMessagesForAppCount(address app) - Total messages from app (length of app's message list)
  • getTotalMessagesForAppUserCount(address app, address user) - Total messages from user in app (length of user's message list in app)
  • getTotalMessagesForAppTopicCount(address app, string topic) - Total messages from app for topic (length of app's message list for topic)
  • getTotalMessagesForAppUserTopicCount(address app, address user, string topic) - Total messages from user for topic in app (length of user's message list for topic in app)

Event Monitoring​

Net emits events for all message activity:

// Direct messages
event MessageSent(
    address indexed sender,
    string indexed topic,
    uint256 messageIndex
);

// App messages
event MessageSentViaApp(
    address indexed app,
    address indexed sender,
    string indexed topic,
    uint256 messageIndex
);

Error Handling​

Net implements custom errors for robust error handling:

  • MsgEmpty() - Reverted when attempting to send empty messages
  • InvalidRange() - Reverted when start index >= end index
  • InvalidStartIndex() - Reverted when start index is out of bounds
  • InvalidEndIndex() - Reverted when end index is out of bounds

TypeScript/JavaScript SDK​

For TypeScript and JavaScript developers, we provide an official SDK with React hooks and client classes. See the net-public repository for documentation and examples.

Resources​